Tools Plus is a set of powerful, yet easy-to-learn productivity libraries for Macintosh programmers using Symantec Corporation’s THINK C/C++, and THINK Pascal. Over 170 high-powered “set and forget” routines let you create your application’s user interface, while Tools Plus maintains it for you and takes care of event management.
With Tools Plus, you have the advantage of enhanced functionality, automation, and full integration of: windows, floating palettes, tool bar, cursors, buttons, picture buttons, scroll bars, editing fields, list boxes, pull-down and hierarchical menus, pop-up menus, the Edit menu, clipboard, alerts, event handling, and more. Once you create your user interface, Tools Plus makes it work. Virtually all Tools Plus routines can be executed with a single line of code.
Using Tools Plus simplifies your programming and accelerates development. You’ll create applications in less time, with less source code, with far fewer bugs, and with more features than if you use ordinary C/C++ or Pascal.
Tools Plus libraries can be compiled into applications intended for System 5 and 6 (running under Finder and MultiFinder™), and System 7.
An Overview of Tools Plus
`````````````````````````
To describe Tools Plus in a single sentence, it’s a “user interface builder/maintainer, and event manager.” Its main function is to let you create a user interface without actually having to maintain it. A simple example of this is the Apple menu. With Tools Plus, you can give your application full reign over desk accessories just by creating the Apple menu with the AppleMenu routine. Tools Plus automatically takes care of any activity pertaining to desk accessories, such as when the user selects a desk accessory from the Apple menu, repositions the accessory by dragging it, clicks buttons or types in the accessory, copies and pastes text in the desk accessory, and eventually closes it. All this is handled automatically by Tools Plus (you don’t have to write any code for it).
The thing that makes all this possible is Components: every routine in the Tools Plus libraries is a reusable, self-contained, and self-maintaining Component designed to be an integral part of your application. Each Tools Plus Component is fully integrated with other Tools Plus Components, and with the Macintosh environment.
The majority of Tools Plus’s routines are dedicated to creating and accessing elements of your application’s user interface, such as a push-button, an editing field or a picture button. Once you have created a user interface element, you can forget about it. Tools Plus takes care of the rest. You can write your application using either Object Oriented Programming (OOP) or procedural (traditional) coding techniques.
Tools Plus’s features integrate with each other according to the User Interface guidelines found in Inside Macintosh. An active editing field, for example, automatically intercepts and processes key-strokes from the keyboard. An editing field’s text can also be affected by the Edit menu, which lets the user Cut, Copy, Paste, and Clear the text, as well as transfer text between your application and other applications and desk accessories via the clipboard. The Edit menu is automatically updated by the user’s actions in the active editing field: when an insertion point is in the field, the Edit menu’s “Cut” and “Copy” selections are disabled, since no text is selected for cutting or copying. You can see how this frees you (the programmer) to do more important things, like writing programs!
Not a Code Generator or Class Library
`````````````````````````````````````
Tools Plus differs in many ways from code generators and class libraries (for object oriented programming). It addresses the need to enhance productivity without inheriting the shortcomings if its predecessors. Class libraries, although incredibly powerful and versatile, demand that you make a heavy investment in time to learn the libraries before you become proficient with them. Tools Plus, on the other hand, is easy to learn. Code generators do just that: they generate code. Even though you don’t have to write the code yourself, you will inevitably have to understand the inner workings of that code. Tools Plus libraries eliminate the need for thousands of lines of code, thereby making your application simpler and easier to maintain
The heart-beat of Tools Plus is the polling routine, which is called by your application (instead of calling the Macintosh toolbox’s GetNextEvent or WaitNextEvent) to obtain events generated by the user, such as typing or mouse-clicks. In fact, all events are obtained this way. The big difference here is that Tools Plus’s polling routine does everything it possibly can before informing your application of an event. Many events are processed internally and are never reported to your application, such as when the user types in an Editing Field (because the field automatically processes the typing). Other events are reported to your application, such as when the user clicks a button.
In contrast to other polling routines such as GetNextEvent or WaitNextEvent, Tools Plus’s polling routine translates the Macintosh’s events into something your application can use right away. So instead of getting a low level “mouse down” event, your application gets a highly informative Tools Plus event such as: the “Save” button was selected in the “Add Customer” window (or button 4 was selected in window 15).
The following example illustrates the difference between ordinary C or Pascal programming, and a program written with Tools Plus. The left column represents the steps a traditional program has to take to detect and process a simple event, whereas the right column has the benefit of Tools Plus. Note that the left column is highly simplified!
Ordinary C or Pascal Programming Programming with Tools Plus
2 Determine the type of event (a = Button Selected event
“mouse-down”) (button 3 in window 15)
3 Determine its location (a
window’s content region)
4 Determine where in the window (a
“control”)
5 Track the mouse in and out of the
control
6 If the mouse button was released
inside the control’s region,
report that the control was
selected. Otherwise ignore the
entire event.
-----------------------------------
= Mouse-down event
in a control (handle is known)
in a window (pointer is known)
Of course, additional steps could be taken in traditional C or Pascal to obtain a window number and button number, but at the expense of more programming.
The Tools Plus Advantage
````````````````````````
There are many advantages to using Tools Plus when you are writing a Macintosh application:
There are many advantages to using Tools Plus when you are writing a Macintosh application:
Tools Plus routines work seamlessly with System 5 and System 6 (when running under Finder and MultiFinder), System 7, and Power Macintoshes (in 68040 emulation mode).
Tools Plus library routines are reusable, self-maintaining components. They promote code reusability by being reusable themselves, and provide a solid application foundation.
Unlike “code generators,” Tools Plus does not demand that you adhere to a rigid design or cumbersome application constraints, nor does it create thousands of lines of code, or demand that you learn complex class libraries. Tools Plus fits in with your programming style, whether your code is procedural or object-oriented. It’s also easy to learn, and easy to use.
Unlike object oriented class libraries that add thousands of lines of code to your application, Tools Plus reduces the need for most of your user-interface code.
You can use the same Tools Plus libraries and support files regardless if you are compiling your application for a plain 68000 processor, or optimizing it for 68020, 68030, or 68040 processors, and/or optimizing it for a math co-processor (68881, 68882 or 68040.)
Instead of using many routines in the Macintosh’s toolbox or class library, you’ll use relatively few Tools Plus routines. You’ll find it easier to program when you can accomplish a given task with fewer routines.
You can typically create elements of the Macintosh’s user-interface, such as windows, a tool bar, palettes, buttons, picture buttons, check boxes, scroll bars, pull-down and hierarchical menus, pop-up menus, list boxes, editing fields, etc., with a single Tools Plus routine. Creating a user-interface becomes a breeze.
The interrelationship between Tools Plus user interface elements is automatically maintained. An illustration of this is when the user is typing in a field in your application, goes to the Apple menu and selects the calculator, performs some calculations and selects the Edit menu’s Copy command, then goes back to your application and chooses the Paste command to paste the calculator’s answer into the field. You, as a programmer, don’t have to code anything to account for the interdependencies between your application’s editing fields, the Edit menu, the Clipboard, the Apple menu, and the calculator.
Tools Plus makes it easier to work with user-interface elements by referencing them by number. In contrast, Macintosh toolbox routines use pointers to reference windows and handles to reference buttons and scroll bars. Your application will be easier to write with Tools Plus because there will be less to remember.
Tools Plus routines are safer to use than Macintosh toolbox routines because they shield you from potential pointer and handle dereferencing problems, and from numerous logical errors.
All Tools Plus routines are self-maintaining. For example, once you have created a button, you can forget it. Tools Plus will let you know when that button is selected by the user, and it will take care of all the work necessary to make the button work (i.e., detecting the event, highlighting the button, tracking the cursor in and out of the button, unhighlighting the button, and reporting the button’s selection).
The revolutionary Event Translator in Tools Plus reports usable events. An example of this is telling your application “the Cancel button in the Search dialog was selected.” This is much simpler than decoding event messages and tracking controls, handles and pointers, as required with ordinary C or Pascal.
Tools Plus routines do a lot of work for you. A single routine can save you writing hundreds of lines of source code making dozens of calls to Macintosh toolbox routines, so you’ll end up writing considerably less source code. They also eliminate the need for thousands of lines of code created by a code generator.
Tools Plus takes care of most of the Macintosh’s user-interface “housekeeping” by automatically handling desk accessories, mouse and keyboard activity, translating and processing events, and telling your application what the user and system are doing. You can focus on writing your application instead of maintaining the user-interface.
With Tools Plus, you will have far fewer bugs because you’ll be writing considerably less code. Applications written with Tools Plus are shorter and simpler to debug and modify, and they also have more readable source code.
Tools Plus is efficient: it requires little memory or disk space, and it executes quickly.
Macintosh standards have been observed as described in Inside Macintosh. This helps ensure that your finished application behaves in a way that all Macintosh applications should.
Tools Plus is easy to learn and use. If you can program in either C/C++ or Pascal, you can use Tools Plus.
Many aspects of the Macintosh’s impeccable user-interface, which you may otherwise have to exclude due to their complexity, can be easily incorporated into your application with Tools Plus.
There are no runtime costs for Tools Plus. That means registered users can distribute applications they have written with Tools Plus without having to pay additional fees or royalties.
The Tools Plus libraries are constantly being expanded, enhanced and optimized, based largely on our users’ requests, so you’ll be benefiting from others’ innovations.
Tools plus is identical for both C/C++ and Pascal, so if you get involved with the other language, you can take your knowledge of Tools Plus with you.
Source code for the Tools Plus libraries is available.
Who can benefit from Tools Plus
```````````````````````````````
Just about anybody writing an application on the Macintosh in C/C++ or can benefit from using Tools Plus. It’s useful to different people for different reasons:
• Novice programmers can start developing applications more readily and
with greater confidence. The task of programming is simplified to
produce quicker results with fewer bugs. And you don’t have to learn
a resource editor (such as Apple’s ResEdit) before you start using
Tools Plus.
• Seasoned programmers can use Tools Plus to develop an application in
less time and with fewer bugs.
What kind of applications can be written with Tools Plus
Tools Plus does not limit you to writing certain kinds of applications, in that it does not preclude you from exercising your technical or creative skills on the Macintosh. It merely helps simplify and manage the user interface and event processing that is so prevalent in Macintosh programs. Varying programming needs are addressed by Tools Plus:
• Quick and Dirty applications can be written in less time. These
programs can have all the features of finished Macintosh applications,
which makes them easier to work with.
• Full fledged applications that are suitable for shrink-wrapping can be
created using Tools Plus.
• Just about any program can be written more quickly and with less
effort by using Tools Plus.
What is Tools Plus not suitable for
```````````````````````````````````
Tools Plus is intended for application developers. It was designed to be the event processing and translating engine within an application, so it definitely cannot be used to create the following:
• Drivers, control panels, INITs or system extensions
• CODE segments that can be incorporated into other applications, such
as 4th Dimension
• Desk accessories. You can still use Tools Plus to write an
application that looks and feels like a desk accessory while running
under System 7.
System Requirements
```````````````````
Computer
````````
Tools Plus makes extensive use of ROM routines that are found only in the 128k ROMs (version 117) or higher. Applications written with Tools Plus will run on the Macintosh 512KE (the “E” stands for enhanced with the new ROMs) or higher. They will not run on a Lisa (also called a Macintosh XL), Macintosh 128K or a standard Macintosh 512K computer. These applications will also run on Power Macintoshes (using 68040 emulation).
Compiler
````````
Tools Plus can be used by programmers developing in THINK C 5.0.4, C/C++ 6.0.1 or later, or THINK Pascal 4.0.2 or later.
System
``````
Applications created with Tools Plus can run under System 5 and 6 (under Finder or MultiFinder) or System 7. We recommend that you use the newest system version because Apple has fixed various bugs and many features have been added to the newer versions.
While developing applications using Tools Plus, you will still have to observe the requirements and limitations of your development environment. THINK C 5.0.4 requires System 5.0 or higher. THINK Pascal 4.0 requires System 6.0.5 or higher. Consult your compiler’s User Manual for details.
Memory
``````
Applications created with Tools Plus can run with less than 100k, depending on the complexity of your application. The overhead associated with Tools Plus is in the neighborhood of 75k.
While developing applications using Tools Plus, you will still have to observe the requirements and limitations of your development environment. THINK C 5.0 and THINK Pascal 4.0 both require 2MB of RAM when using System 7. Consult your compiler’s User Manual for details.
Disk Space
``````````
Tools Plus’s libraries and related files require only a few hundred K of disk space. When compiled, Tools Plus will add less than 75k to your application’s size.
While developing applications using Tools Plus, you will still have to observe the requirements and limitations of your development environment. THINK C 5.0 and THINK Pascal 4.0 both require about 2MB of disk space.
Finished Applications
`````````````````````
Please be aware that you, as a programmer, have the capacity to write applications that have requirements far in excess of Tools Plus’s minimum system requirements. It’s possible that you may choose to write a program that requires a math co-processor, System 7, 20 megabytes of RAM, and a pair of 20 inch color monitors. Be aware that your finished application will likely have needs that exceed Tools Plus’s minimum requirements.
Tools Plus Source Code and Site Licensing
`````````````````````````````````````````
Complete source code is available for the set of Tools Plus libraries. This offer is intended for (but not limited to):
• entities that must assure their autonomy by not relying on closed
third party products
• developers that need to broaden Tools Plus’s scope
Tools Plus source code is heavily commented. Pricing and Source Code Licensing information can be obtained by contacting Water’s Edge Software. Water’s Edge Software also offers Site Licenses at an appropriately reduced pricing structure. Please contact Water’s Edge Software for details.
Assumptions made when writing this manual
`````````````````````````````````````````
Several assumptions have been made when writing this manual:
• You are already a C, C++ or Pascal programmer, or are learning to be
one on your own. This manual does not teach you how to program in C
or Pascal, nor does it teach you how to use the Macintosh’s toolbox
routines. It merely teaches you how to use Tools Plus.
• This manual makes no attempt to teach you how to use THINK C/C++ or
THINK Pascal. Please consult your THINK C/C++ or THINK Pascal User
Manual in such matters, or contact the manufacturer, Symantec
Corporation.
• This manual makes no attempt to teach you how to use ResEdit, or any
other application or tool that is part of your development
environment.
• You already know how to use the Macintosh, and are familiar with its
terms such as clicking, dragging, selecting, etc.
• This manual does not assume that all programmers and users are male.
For the sake of easier reading, the term “he” implies either gender
within this manual.
Convensions used throughout this manual
```````````````````````````````````````
1) Each Tools Plus routine is documented with both a C header and
Pascal interface.
2) Source code examples are given in Pascal, just like Inside
Macintosh. In situations where the C source code differs (usually
due to differences in record structure), an example is also provided
in C.
3) The Pascal terms function and procedure are used throughout this
manual. For the benefit of C programmers, a function is a routine
that returns a value. The following table provides an example:
C “Procedure”: pascal void DeleteListBox(short ListBox);
Pascal Function : function FirstWindowNumber: integer;
C “Function” : pascal short FirstWindowNumber(void);
4) Important information is highlighted with notes and warnings...
Note: A note that may be interesting or useful (don’t skip these)
Warning: A point you need to be cautious about.
5) This manual is not intended to replace Inside Macintosh or its
equivalent. It does not detail the fundamentals of Macintosh
programming, such as screen versus window co-ordinate systems (local
versus global), commonly used structures (points, rectangles,
grafPort, etc.), using the Macintosh toolbox, etc.
6) For the benefit of new programmers, portions of this manual address
the basics of building a Macintosh application, such as some
differences between Finder and MultiFinder and how to complete a
double-clickable application.
Software Updates
````````````````
Registered Tools Plus users are entitled to take advantage of our Software Update Program, which offers free updates as well as updates at reduced prices. We recommend that you periodically check the Water’s Edge Software bulletin board on CompuServe (see the Technical Support chapter for details) to determine the latest version and information on how to upgrade.
Water’s Edge Software is enhancing Tools Plus on an on-going basis by optimizing code and adding new features. We will inform registered users of newly available updates either by mail or by electronic mail (if you provide us your e-mail account number, we will send you update information electronically).
Note: In order to ensure uninterrupted software update notification,
please inform us if your mailing address or e-mail account
changes.
Your Development Environment
````````````````````````````
This manual makes no attempt to teach you how to use your development environment, THINK C/C++ or THINK Pascal. Please consult your THINK C/C++ or THINK Pascal User Manual in such matters, or contact the manufacturer, Symantec Corporation.
Every Macintosh developer should have a copy of ResEdit, Apple’s resource editor application. It’s easy to use, indispensable, and best of all, free from your Apple dealer. Always get the latest version (2.1.1 at this writing), since it’s always being upgraded and improved. Beginners can get by without ResEdit, but you won’t want to.
For your information (recommended reading)
``````````````````````````````````````````
For any Macintosh programmer, we suggest you either own or have access to the entire series of “Inside Macintosh” technical reference guides by Addison Wesley. They are the definitive Macintosh bible for programmers of any caliber. They’re worth their weight in midnight oil if you want to get into serious Macintosh programming.
Another indispensable tool is THINK Reference, an on-line reference manual for C or Pascal programmers. It describes all the Mac’s data structures, variables, constants, functions and procedures. It also has valuable programming tips.
To program a Macintosh, you’ll have to know the basics of the Macintosh toolbox. We recommend the following:
• Get familiar with QuickDraw by reading chapter 6 of Inside Macintosh
Volume I (or equivalent). This section details drawing in the
Macintosh’s graphic environment.
• Get familiar with the Font Manager by reading chapter 7 of Inside
Macintosh Volume I (or equivalent). This section deals with drawing
text on the Macintosh’s screen
• Have a working knowledge of the Macintosh’s Memory Manager (chapter 3
of Inside Macintosh Volume I, or equivalent). This section deals with
pointers, handles, and memory fragmentation.
• The thing that differentiates a good Macintosh application from the
rest of the world is that a user will find the program easy to learn
and use. These benefits can be attributed greatly to a consistent and
well-designed user interface. Learn the dos and don’ts of graphic
user interface (GUI) design, then learn some more! Chapter 7 of
Inside Macintosh Volume I introduces you to the Macintosh’s GUI and
it’s standards. Another good way of learning is to get exposure to
(and become familiar with) a wide range of Macintosh applications.
You’ll spot the good ones and the not so good ones after a while!
